home *** CD-ROM | disk | FTP | other *** search
/ Chip 1998 September / CHIP Eylül 1998.iso / Slackwar / docs / TeTeX-HOWTO < prev    next >
Text File  |  1997-09-02  |  85KB  |  1,875 lines
  1.   The teTeX HOWTO: The Linux-teTeX Local Guide
  2.   Robert Kiesling
  3.   v2.9.1, 21 August 1997
  4.  
  5.   This document covers the basic installation and usage of the teTeX TeX
  6.   and LaTeX implementation under the major U.S. Linux distributions, and
  7.   auxiliary packages like Ghostscript.  Contents of the teTeX HOWTO: The
  8.   Linux-teTeX Local Guide are Copyright (c) 1997 by Robert A. Kiesling.
  9.   Permission is granted to copy this document, in whole or in part, pro¡
  10.   vided that credit is given to the author and the Linux Documentation
  11.   Project. Registered trademarks are the property of their respective
  12.   holders.  Please send all complaints, suggestions, errata, and any
  13.   miscellany to kiesling@terracom.net, so I can keep this document as
  14.   complete and up to date as possible.
  15.  
  16.   1.  Introduction.
  17.  
  18.   FAQ No. 1.  My computer just ate NINE high density diskettes' worth of
  19.   data.  WHAT HAPPENED?
  20.  
  21.   Answer: Installing teTeX on Chanel3, my Compaq laptop, was like
  22.   dropping a 20-foot concrete bridge section exactly into place from a
  23.   height of 50 feet.  teTeX is a big package. Even so, it is a
  24.   moderately complete implementation of TeX 3.1415 and LaTeX 2e for
  25.   Linux systems.  TeX is a big subject anyway, so you can expect to
  26.   spend the rest of your computing career keeping up-to-date on the
  27.   latest in the world of TeX.  That is to say, installing and using
  28.   teTeX is not for the faint of heart.  Nor is it for day trippers.
  29.   This package requires serious quality time.
  30.  
  31.   Thomas Esser, the author of teTeX, has gone to great lengths to make
  32.   the package fast, complete, and easy to use.  Because TeX is
  33.   implemented for practically every serious computer system in the
  34.   world---and quite a few ``non-serious'' ones---implementors must
  35.   provide the installation facilities for all of them.  This accounts in
  36.   part for teTeX's size.  It also accounts for the fact that the pieces
  37.   necessary to make a workable teTeX installation are spread all over
  38.   your friendly neighborhood CTAN archive.
  39.  
  40.   CTAN is the Comprehensive TeX Archive Network, a series of anonymous
  41.   FTP sites which archive TeX programs, macros, fonts, and
  42.   documentation.  You'll probably become familiar with at least one CTAN
  43.   site.  In this document, a pathname like ~CTAN/contrib/pstricks means
  44.   ``look in the directory contrib/pstricks of your nearest CTAN site.''
  45.   See section ``Appendix A'' for a current list of CTAN sites and their
  46.   mirror sites.
  47.  
  48.   Fortunately, some considerate Linux Distribution implementors have
  49.   assembled the necessary pieces for us.  teTeX comes with all the major
  50.   Linux distributions.
  51.  
  52.   However, if you don't have the Slackware, RedHat, or Debian GNU/Linux
  53.   distribution, you can install teTeX from its official CTAN
  54.   distribution.  In some cases this may be more desirable.  See Section
  55.   3 for details.
  56.  
  57.   If you already have teTeX installed on your system and want to jump
  58.   directly into figuring out how to use it, skip this section and the
  59.   next, and go directly to section ``Using teTeX''.
  60.  
  61.   2.  What is TeX?  What is LaTeX?  What is teTeX?
  62.  
  63.   teTeX is an implementation of TeX for UNIX systems.  It is the work of
  64.   Thomas Esser, te@informatik.uni-hannover.de.  In the Linux versions of
  65.   teTeX, the executable programs themselves run under Linux and the
  66.   fonts are provided in form usable by the Linux-teTeX system.  (The
  67.   sections covering teTeX installation concentrate on the i386 versions
  68.   of Linux.  Installing teTeX for MkLinux or Linux for the Alpha should
  69.   require only substituting the appropriate binary-program archive in
  70.   the installation process.)  The rest of the code, TeX and LaTeX
  71.   itself, is portable across various machines.
  72.  
  73.   In addition to the executable programs, the distribution includes all
  74.   of the TeX and LaTeX package, metafont and its sources, bibtex(1),
  75.   makeindex(1), and all of the documentation... more than 4 megabytes'
  76.   worth.  The documentation covers everything you will forseeably need
  77.   to know to get started.  So, you should install all of the documents.
  78.   Not only will you eventually read them, the documents themselves
  79.   provide many examples of ``live'' TeX and LaTeX code.
  80.  
  81.   In comparison with other implementations of TeX, the installation of
  82.   teTeX is almost trivial, even without the Linux distribution packages,
  83.   if you don't count the effort necessary acquire the distributions via
  84.   anonymous FTP or insert and remove several dozen distribution
  85.   diskettes by hand.  If your teTeX distribution arrived on a CD-ROM,
  86.   even less effort is required to install it.
  87.  
  88.   TeX is a typesetting system developed by Professor Donald Knuth of
  89.   Stanford University.  It is a lower-level typesetting language that
  90.   powers all of the higher-level packages like LaTeX.  Essentially,
  91.   LaTeX is a set of TeX macros which provide convenient, predefined
  92.   document formats for end users.  If you like the formats provided by
  93.   LaTeX, you may never need to learn bare-bones TeX programming.  The
  94.   difference between the two languages is like the difference between
  95.   assembly language and C.  You can have the speed and flexibility of
  96.   TeX, or the convenience of LaTeX.  Which brings us to the next answer,
  97.  
  98.   Answer: You have it backwards! I want to know what exactly I need to
  99.   get before I can have TeX on my system!
  100.  
  101.   It's important to remember that TeX only handles the typesetting part
  102.   of the document preparation.  Generating output with TeX is like
  103.   compiling source code into object code, which still needs to be
  104.   linked.  You prepare an input file with a text editor -- what most
  105.   people think of as ``word processing'' -- and typeset the input file
  106.   document with TeX to produce a device-independent output file, called
  107.   a .dvi file.
  108.  
  109.   You also need output drivers for your printer and video display.
  110.   These output drivers translate TeX's .dvi output to display your
  111.   typeset document on the screen or on paper.  This software is
  112.   collectively known as ``dviware.''  For example, TeX itself only makes
  113.   requests for fonts.  It is up to the .dvi output translator to provide
  114.   the actual font to the display device if necessary, regardless of
  115.   whether it is the screen or a printer.  This extra step may seem
  116.   overly complicated, but the abstraction allows documents to display
  117.   the same on different devices with no change to the original document.
  118.  
  119.   In fact, much of TeX's, and therefore LaTeX's, complexity, arises from
  120.   its implementation of various font systems, and the way these fonts
  121.   are specified.  A major improvement of LaTeX 2e over its predecessor
  122.   was the way users specify fonts, the former New Font Selection Scheme.
  123.   (See the sections ``Characters and type styles'' and ``Using
  124.   PostScript Fonts''.)
  125.  
  126.   teTeX comes distributed with about a dozen standard fonts preloaded,
  127.   which is enough to get you started.  Also provided are the font
  128.   metrics descriptions, in .tfm (TeX font metric) files.  To generate
  129.   the other fonts you will need, it is simply a matter of installing the
  130.   metafont sources.  teTeX's .dvi utilities will invoke metafont
  131.   automatically and generate the Computer Modern fonts you need, on-the-
  132.   fly.
  133.  
  134.   By the way, the letters of the word ``TeX'' are Greek, tau-epsilon-
  135.   chi.  This is not a fraternity.  Instead, it is the root of the Greek
  136.   word, techne, which means art and/or science.  ``TeX'' is not
  137.   pronounced like the first syllable in "Texas."  The chi has no English
  138.   equivalent, but TeX is generally pronounced so that it rhymes with
  139.   ``yecch,'' to use Professor Knuth's example from The TeXBook (see
  140.   below).  When writing, "TeX," on character devices, always use the
  141.   standard capitalization, or the \TeX{} macro in typesetting.  This is
  142.   how TeX is distinguished from other typesetting systems.
  143.  
  144.   Speaking of typing, any of the editors which work under Linux---
  145.   nvi(1), jed(1), joe(1), jove(1), vi(1), vim(1), stevie(1), emacs(1),
  146.   microemacs---will work to prepare a TeX input file, as long as the
  147.   editor reads and writes plain-vanilla ASCII text.  My preference is
  148.   emacs(1), the GNU version.  There are several reasons for this:
  149.  
  150.   ╖  Emacs' TeX and LaTeX modes obviate the need for a stand-alone TeX
  151.      shell.
  152.  
  153.   ╖  Emacs can automatically insert TeX-style, ``curly quotes,'' as you
  154.      type, rather than the "ASCII-vanilla" kind.
  155.  
  156.   ╖  Emacs has integrated support for texinfo and makeinfo, a hypertext
  157.      documentation system.
  158.  
  159.   ╖  Emacs is widely supported.  Version 19.34, for example, is included
  160.      in the major U.S. Linux distributions.
  161.  
  162.   ╖  Emacs does everything except butter the toast in the morning.
  163.  
  164.   ╖  Emacs is free.
  165.  
  166.   There's a lot of software to assemble.  In the meantime, you can start
  167.   in ``learning'' TeX and LaTeX.  Remember that teTeX and the font
  168.   packages have been designed as two separate entities: The teTeX
  169.   executable programs and shell scripts, as distributed with Linux, have
  170.   been built specifically for the system, but the CM, DC, American
  171.   Mathematical Society, or other font distributions work on many
  172.   different platforms.  While you are working on assembling the files,
  173.   you can take a few breaks to locate some of the documentation you will
  174.   need.
  175.  
  176.   2.1.  Resources for further information.
  177.  
  178.   There are user manuals available both commercially and via the
  179.   Internet.  Judging by the number of mentions they receive in the
  180.   Usenet comp.text.tex newsgroup, the most useful---and
  181.   definitive---commercially available texts for beginners are:
  182.  
  183.   LaTeX: A Document Preparation System, by Leslie Lamport, 272 pp.  If
  184.   you're using LaTeX instead of plain TeX (highly recommended), this is
  185.   the definitive reference.
  186.  
  187.   If you must use plain TeX, The TeXBook by Donald Knuth, 483 pp., is
  188.   the definitive reference.  It is also necessary if you plan to do any
  189.   serious class, package, or macro writing for LaTeX.
  190.  
  191.   The LaTeX Companion, by Michel Goosens, Frank Mittelbach, and
  192.   Alexander Samarin, 530 pp., is more advanced than the Lamport, above.
  193.   If you are approaching TeX or LaTeX for the first time, you may feel
  194.   lost reading this.  (I was.)  However, when you need to add extension
  195.   packages, like PSNFSS (See the section titled, ``Using PostScript
  196.   fonts''.), or bibtex(1), a bibliography indexing program, this book is
  197.   one of the most highly regarded on the market.
  198.  
  199.   At your nearest CTAN site you can retrieve these documents for free:
  200.  
  201.   The Not So Short Introduction to LaTeX2e, by Tobias Oetiker, Hubert
  202.   Partl, Irene Hyna, and Elisabeth Schlegl, 69 pp.  This wonderful
  203.   document is located at ~CTAN/packages/TeX/info/lshort/*.
  204.  
  205.   You can get a PostScript or .dvi version of the document ready for
  206.   printing, or the native LaTeX document.  There is also a version
  207.   available in German: lkurz.*. Make sure to read the README file before
  208.   assembling!
  209.  
  210.   A Gentle Introduction to TeX: A Manual for Self-Study, by Michael
  211.   Doob, 91 pp.  You can find this document at:
  212.   ~CTAN:packages/TeX/info/gentle.tex. Almost of necessity, this document
  213.   covers less ground than its LaTeX counterpart, above.  However, it
  214.   will get you to the same place as the LaTeX manuals. If you must use
  215.   plain TeX for your documents, this document clarifies many of the
  216.   complexities of plain TeX and makes its use almost easy.
  217.  
  218.   ``IMPRINT: The Newsletter of Digital Typography,'' edited by Robert
  219.   Kiesling.  I realize that this is BLATANT and SHAMELESS self-
  220.   promotion.  But, you should know anyway, that IMPRINT is a free,
  221.   ASCII-text newsletter which is available via e-mail.  IMPRINT appears
  222.   approximately monthly and covers a broad range of text processing and
  223.   digital imaging topics, both beginning and advanced.  Many of the
  224.   items covered apply directly or indirectly to TeX'ing.  The emphasis
  225.   is on production of industry-standard typeset and printed material.
  226.   To subscribe to IMPRINT, send a brief, human-readable message to me at
  227.   imprint@macline.com.
  228.  
  229.   The LaTeX Catalogue is a bibtex(1) database of available LaTeX
  230.   packages, compiled and maintained by Graham Williams.  It's included
  231.   with teTeX, and the most recent version is available on the World Wide
  232.   Web.  Do you need a package that prints borders, or makes margin
  233.   notes?  You'll find that the package you need is listed here.  The
  234.   LaTeX Catalogue is located in your local teTeX library in the
  235.   directory teTeX/texmf/doc/Catalog, and on the Web at
  236.   http://cbr.dit.csiro.au/~gjw.  See section ``LaTeX extension packages
  237.   and other resources'' for further details about LaTeX packages.
  238.  
  239.   Thomas Merz's Ghostscript Manual, which is the Ghostscript appendix of
  240.   his book, PostScript  Acrobat/PDF: Applications, Troubleshooting, and
  241.   Cross-Platform Publishing. It is available from the Ghostscript Home
  242.   Page (see the section ``Ghosctscript V. 5.03''), or from Merz's home
  243.   page, http://www.muc.de/~tm/.
  244.  
  245.   There are, of course, other guides available to using TeX and LaTeX.
  246.   They cover different aspects of these systems to varying degrees.  The
  247.   reference documents cited above, however, are the most comprehensive
  248.   in scope that I have seen and are aimed at beginners (or near-
  249.   beginners).
  250.  
  251.   If the going gets especially tough, you can probably do a little extra
  252.   shopping at Office Max, Office Depot, Staples, or your local
  253.   stationer, and pick up several reams of three-hole punched, photocopy
  254.   paper, two or three, three-inch binders, and some index tabs.  When it
  255.   comes time to print the documents, you'll need a place to keep them,
  256.   and they seem to be more useful if they are kept on paper.  This must
  257.   be one of the stranger phenomena of technical documentation.
  258.  
  259.   You will note, however, that the references mentioned above are
  260.   hardware-independent.  They won't tell you a thing about running teTeX
  261.   specifically.  Many of them, in fact, refer to some mythical ``Local
  262.   Guide.''  This, and several of the documents that come bundled with
  263.   teTeX, comprise the less-than-mythical Local Guide to installing and
  264.   operating teTeX with Linux.
  265.  
  266.   3.  Installation notes.
  267.  
  268.   All of the major Linux distributions include packaged versions of
  269.   teTeX, and each distribution has its own idiosyncrasies.  The
  270.   packaging methods of each distribution are, for the most part,
  271.   incompatible.  If you try to install teTeX from another distribution,
  272.   you may succeed in installing the package, but you're certain to mess
  273.   up the package-management database on your system.  When installing
  274.   teTeX, please consult the section below that corresponds to your Linux
  275.   distribution.
  276.  
  277.   Installing teTeX is surprisingly easy for a package of this magnitude.
  278.   This document covers only the major free U.S. Linux distributions,
  279.   because I haven't had time to obtain or install European Linux
  280.   distributions like S.u.S.E.
  281.  
  282.   However, the generic, teTeX distribution isn't any harder to install
  283.   than the Linux packages.  See section ``Generic CTAN distribution'',
  284.   below.
  285.  
  286.   You should consider installing the generic teTeX distribution from the
  287.   CTAN archives if:
  288.  
  289.   ╖  Your system isn't based on one of the standard Linux distributions.
  290.  
  291.   ╖  You don't have root privileges on your system.
  292.  
  293.   ╖  You want or need to have the very latest version of teTeX, or
  294.      LaTeX.
  295.  
  296.   ╖  You don't have enough disk space available for a full installation.
  297.  
  298.   ╖  You want to install teTeX somewhere instead of the /usr file
  299.      system.
  300.  
  301.   ╖  You would like to share your teTeX installation with other UNIX
  302.      variants or platforms on a network.  In this case, you should
  303.      strongly consider installing from the source distribution.  See
  304.      section ``Installing the source distribution'', below.
  305.  
  306.   ╖  You want the latest versions of teTeX's public domain Type 1 fonts,
  307.      which are significantly better than the fonts included in earlier
  308.      releases.
  309.  
  310.   A complete installation of the binary distribution requires 40-50 Mb
  311.   of disk space, and building the distribution from the source code
  312.   takes about 75 Mb, so you should make sure that the disk space is
  313.   available before you start.  You don't need to have the gcc(1)
  314.   compiler or the X Windows System installed (although X certainly helps
  315.   because it is much easier to preview documents on-screen).  All you
  316.   need is an editor that is capable of producing plain ASCII, text (see
  317.   section 2).  What could be simpler?
  318.  
  319.   Ghostscript V. 5.03 allows printing of PostScript documents on non-
  320.   PostScript printers, and allows previewing of PostScript documents on
  321.   VGA monitors and X Window System displays.  If you already have a
  322.   PostScript printer, you won't need Ghostscript simply to print
  323.   PostScript documents.  Ghostscript has many other capabilities,
  324.   however, which are beyond the scope of this HOWTO.
  325.  
  326.   APSFILTER can automate document post processing and printing, and make
  327.   life with your printer a lot easier.  See the section titled
  328.   ``APSFILTER''.
  329.  
  330.   For information on how to install a printer daemon and generally
  331.   configure printers for Linux, see the section titled ``The lpd(8)
  332.   daemon'', and consult the Printing-HOWTO.
  333.  
  334.   3.1.  Generic CTAN distribution, V. 0.4.
  335.  
  336.   You can retrieve the files from one of the CTAN archives listed in
  337.   section ``Appendix A''.  In the examples below, the files were
  338.   retrieved from the CTAN archive at ftp.tex.ac.uk.
  339.  
  340.   3.1.1.  Installing the binary distribution.
  341.  
  342.   3.1.1.1.  Minimal installation.
  343.  
  344.   First, FTP to ftp.tex.ac.uk and cd to the directory
  345.  
  346.   ctan/tex-archive/systems/unix/teTeX/distrib/
  347.  
  348.   Retrieve the files
  349.  
  350.   INSTALL.bin
  351.   install.sh
  352.  
  353.   and place them in the top-level directory where you want to install
  354.   teTeX, for example, /var/teTeX if you plan to install teTeX in the
  355.   /var file system.
  356.  
  357.   Print out the INSTALL.bin file.  Keep this file handy, because it
  358.   describes how to install a minimal teTeX installation.  The minimal
  359.   installation requires only 10-15 MB of disk space, but it is
  360.   recommended that you install the complete teTeX package if at all
  361.   possible.  For a minimum installation, you'll need the files
  362.  
  363.   ctan/tex-archive/systems/unix/teTeX/distrib/base/latex-base.tar.gz
  364.   ctan/tex-archive/systems/unix/teTeX/distrib/base/tetex-base.tar.gz
  365.  
  366.   You'll also need one of two archives which contain the executable
  367.   teTeX programs.  Retrieve the archive file
  368.  
  369.   ctan/tex-archive/systems/unix/teTeX/distrib/binaries/i386-linux.tar.gz
  370.  
  371.   if your system uses the Linux ELF shared libraries, ld.so(1) of at
  372.   least version 1.73, and clibs of at least version 5.09.  If it
  373.   doesn't, retrieve the archive
  374.  
  375.   ctan/tex-archive/systems/unix/teTeX/distrib/binaries/i386-linuxaout.tar.gz
  376.  
  377.   which is compiled for systems that use the older, a.out-format static
  378.   libraries.
  379.  
  380.   Then, following the instructions in the file INSTALL.bin, execute the
  381.   command
  382.   sh ./install.sh
  383.  
  384.   while in the top-level teTeX installation directory. (Make sure that
  385.   the teTeX archives are located there, too.)  After a few moments, the
  386.   installation program will warn you that you are missing some of the
  387.   teTeX packages.  However, if you're planning only a minimal teTeX
  388.   installation, you should ignore the warnings and proceed.  To config¡
  389.   ure the basic teTeX system, see section ``Base system configuration'',
  390.   below.
  391.  
  392.   To install the remaining packages, see the next section.
  393.  
  394.   3.1.1.2.  Complete installation.
  395.  
  396.   To perform a complete teTeX installation, retrieve the archive files
  397.   listed in the previous section, as well as the following files:
  398.  
  399.   ctan/tex-archive/systems/unix/teTeX/distrib/doc/ams-doc.tar.gz
  400.   ctan/tex-archive/systems/unix/teTeX/distrib/doc/bibtex-doc.tar.gz
  401.   ctan/tex-archive/systems/unix/teTeX/distrib/doc/eplain-doc.tar.gz
  402.   ctan/tex-archive/systems/unix/teTeX/distrib/doc/fonts-doc.tar.gz
  403.   ctan/tex-archive/systems/unix/teTeX/distrib/doc/general-doc.tar.gz
  404.   ctan/tex-archive/systems/unix/teTeX/distrib/doc/generic-doc.tar.gz
  405.   ctan/tex-archive/systems/unix/teTeX/distrib/doc/latex-doc.tar.gz
  406.   ctan/tex-archive/systems/unix/teTeX/distrib/doc/makeindex-doc.tar.gz
  407.   ctan/tex-archive/systems/unix/teTeX/distrib/doc/metapost-doc.tar.gz
  408.   ctan/tex-archive/systems/unix/teTeX/distrib/doc/programs-doc.tar.gz
  409.   ctan/tex-archive/systems/unix/teTeX/distrib/fonts/ams-fonts.tar.gz
  410.   ctan/tex-archive/systems/unix/teTeX/distrib/fonts/dc-fonts.tar.gz
  411.   ctan/tex-archive/systems/unix/teTeX/distrib/fonts/ec-fonts.tar.gz
  412.   ctan/tex-archive/systems/unix/teTeX/distrib/fonts/misc-fonts.tar.gz
  413.   ctan/tex-archive/systems/unix/teTeX/distrib/fonts/postscript-fonts.tar.gz
  414.   ctan/tex-archive/systems/unix/teTeX/distrib/fonts/sauter-fonts.tar.gz
  415.   ctan/tex-archive/systems/unix/teTeX/distrib/goodies/amstex.tar.gz
  416.   ctan/tex-archive/systems/unix/teTeX/distrib/goodies/bibtex.tar.gz
  417.   ctan/tex-archive/systems/unix/teTeX/distrib/goodies/eplain.tar.gz
  418.   ctan/tex-archive/systems/unix/teTeX/distrib/goodies/latex-extra.tar.gz
  419.   ctan/tex-archive/systems/unix/teTeX/distrib/goodies/metapost.tar.gz
  420.   ctan/tex-archive/systems/unix/teTeX/distrib/goodies/pictex.tar.gz
  421.   ctan/tex-archive/systems/unix/teTeX/distrib/goodies/pstricks.tar.gz
  422.   ctan/tex-archive/systems/unix/teTeX/distrib/goodies/texdraw.tar.gz
  423.   ctan/tex-archive/systems/unix/teTeX/distrib/goodies/xypic.tar.gz
  424.  
  425.   All of these files should be placed in the top-level directory where
  426.   you want teTeX to reside.  As with the minimal installation, execute
  427.   the command
  428.  
  429.   sh ./install.sh
  430.  
  431.   3.1.1.3.  Base system configuration.
  432.  
  433.   The install.sh script, after determining which teTeX archive series
  434.   are present, will present you with a menu of options.  The only
  435.   setting you need to make at this point is to set the top-level
  436.   directory where you want teTeX installed, by selecting the ``D''
  437.   option.  You must, of course, choose a directory in whose parent
  438.   directory you have write permissions.  For example, if you are
  439.   installing teTeX in your home directory, you would specify the teTeX
  440.   installation directory as
  441.  
  442.   /home/john.q.public/teTeX
  443.  
  444.   and, after returning to the main menu, select ``I'' to proceed with
  445.   the installation.  Note that the directory must not exist already: the
  446.   install.sh script must be able to create it.
  447.  
  448.   An option which you should consider enabling, is setting an
  449.   alternative directory for generated fonts.  Even if you plan to use
  450.   only PostScript-format, Type 1 scalable fonts, occasionally you'll
  451.   process a file that requires the Computer Modern fonts.  Enabling this
  452.   option requires that you enter the directory to use.  You must have
  453.   write permissions for the parent directory.  Following the example
  454.   above, you could specify
  455.  
  456.   /home/john.q.public/texfonts
  457.  
  458.   or, if you want the generated fonts to be accessible by all users on
  459.   the system, specify a directory like
  460.  
  461.   /var/texfonts
  462.  
  463.   I would recommend that you not, however, use the default
  464.   /var/tmp/texfonts directory for this option, because the generated
  465.   fonts could be deleted after the next reboot, and the fonts will need
  466.   to be generated again the next time they're needed.
  467.  
  468.   After you've selected the option ``I'', and install.sh has installed
  469.   the archives, set various permissions, and generated its links and
  470.   format files, the program will exit with a message telling you to add
  471.   the teTeX binary directory to your $PATH environment variable, and the
  472.   directories where the man pages and info files reside to your $MANPATH
  473.   and $INFOPATH environment variables.  For example, add the statements
  474.  
  475.   export PATH=$PATH:"/home/john.q.public/teTeX/bin"
  476.   export MANPATH=$MANPATH":/home/john.q.public/teTeX/man"
  477.   export INFOPATH$=INFOPATH":/home/john.q.public/teTeX/info"
  478.  
  479.   to your ~/.bash_profile if you use bash(1) as your shell, or to your
  480.   ~/.profile if you use another shell for logins.
  481.  
  482.   Log out, and then log in again, so the environment variables are
  483.   registered.  Then, run the command
  484.  
  485.   texconfig confall
  486.  
  487.   to insure that the installation is correct.
  488.  
  489.   Next, you can configure teTeX for you specific hardware.  See section
  490.   ``Post-installation configuration details'', below.
  491.  
  492.   3.1.2.  Installing the source distribution.
  493.  
  494.   To install teTeX V. 0.4 from the source code, ftp to a CTAN site like
  495.   ftp://ftp.tex.ac.uk and retrieve the files
  496.  
  497.   ctan/tex-archive/systems/unix/teTeX/distrib/INSTALL.src
  498.   ctan/tex-archive/systems/unix/teTeX/distrib/sources/README.texmf-src
  499.   ctan/tex-archive/systems/unix/teTeX/distrib/sources/teTeX-lib-0.4pl8.tar.gz
  500.   ctan/tex-archive/systems/unix/teTeX/distrib/sources/teTeX-src-0.4pl7.tar.gz
  501.  
  502.   Read over the instructions in INSTALL.src, then su to root and unpack
  503.   the files in a directory for which you have read-write-execute
  504.   permissions.
  505.  
  506.   Remember to use the p argument to tar(1), and also remember to unset
  507.   the noclobber option of bash(1).  You can do this with the
  508.   counterintuitive command
  509.  
  510.   set +o noclobber
  511.  
  512.   Note that the argument +o to set unsets a variable, just exactly back¡
  513.   wards from what you might expect.
  514.  
  515.   The file teTeX-lib-0.4pl8.tar.gz will create the directory create the
  516.   directory teTeX-src-0.4 Print out the file INSTALL.src and keep it
  517.   nearby for the following steps. cd to the ./teTeX-src-0.4 directory,
  518.   and, per the instructions in the INSTALL.src file, edit to the
  519.   absolute path of the parent teTeX directory.  This will be the
  520.   subdirectory teTeX of the directory where you unpacked the source and
  521.   library archives.  For example, if you unpacked the archives in your
  522.   home directory, you would set TETEXDIR to
  523.  
  524.   /home/john.q.public/teTeX
  525.  
  526.   The rest of the Makefile options are pretty generic.  With gcc(1) ver¡
  527.   sion 2.7.2 and later, you should not need to make any further adjust¡
  528.   ments unless you have a non-standard compiler and library setup, or
  529.   want the compiler to perform some further optimizations, or for some
  530.   other reason.  Check that the USE_DIALOG, USE_NCURSES, and
  531.   HAVE_NCURSES variables are set correctly for your system, because the
  532.   dialog program needs the ncurses library to be installed.  A
  533.   ncurses(3x) library is included in the source distribution, so the
  534.   default values in the Makefile should work fine.  If you can't get
  535.   ncurses(3x) to compile or link, texconfig(1) can also be run from the
  536.   command line.
  537.  
  538.   If you've done everything correctly up to this point, you should be
  539.   able to type make world in the top-level source directory, and relax
  540.   until the teTeX executables are built.  This can take a few hours.
  541.  
  542.   After the build has completed, set the environment variables $PATH,
  543.   $MANPATH, and $INFOPATH to include the teTeX directories.  The
  544.   statements which would be added to the file ~/.bash_profile, in the
  545.   example, above, would be
  546.  
  547.   export PATH=$PATH":/home/john.q.public/teTeX/bin/i386-linux"
  548.   export MANPATH=$MANPATH":/home/john.q.public/teTeX/man"
  549.   export INFOPATH=$INFOPATH":/home/john.q.public/teTeX/info"
  550.  
  551.   The $PATH variable is different in the source distribution than in the
  552.   binary distribution.  Note that here the path to the binaries is
  553.   teTeX/bin/i386-linux instead of simply teTeX/bin as in the binary dis¡
  554.   tribution.
  555.  
  556.   At this point you can run texconfig confall to ensure that the paths
  557.   have been set correctly, and then proceed to configure teTeX as in the
  558.   binary distribution.  See the section ``Post-installation
  559.   configuration details'', below.
  560.  
  561.   3.2.  Linux packages.
  562.  
  563.   3.2.1.  Slackware 3.2.
  564.  
  565.   First, ftp to your nearest Linux archive site.  Mine is
  566.   wuarchive.wustl.edu. Then find the directory with the Slackware
  567.   distribution diskettes.  On wuarchive.wustl.edu, this is
  568.  
  569.   systems/linux/sunsite/distributions/Slackware/slakware/.
  570.  
  571.   Linux sites which mirror sunsite.unc.edu will store these diskettes in
  572.   the directory distributions/Slackware/slakware/.  teTeX, the full
  573.   package, is contained on the Slackware disk series t. So, grab all
  574.   nine disks' worth of the t series, disks t1 - t9. Be sure to keep them
  575.   in order, too.  Either store the files in separate subdirectories
  576.   labeled t1 - t9 on a hard drive partition, or on diskettes, and label
  577.   the diskettes t1 through t9. We're going to install them by hand.
  578.  
  579.   This isn't difficult.  The Slackware installer creates the directories
  580.   and unpacks the files.  It also provides descriptions of each module
  581.   in the distribution, which allows you to decide whether you want to
  582.   install it or not.  In the case of teTeX, however, you are simply
  583.   going to install everything, because that's what you should do anyway.
  584.  
  585.   Let's assume that you have all nine diskettes' worth of the Slackware
  586.   teTeX distribution ready at hand, organized as described above.
  587.   You'll have a lot of files which have the extension .tgz.  This is
  588.   shorthand for a tar(1) archive compressed with gzip(1). The names all
  589.   fit the 8+3 filename limitations of MS-DOG.  Aren't you glad you
  590.   decided to scrap your DOG partitions and install Linux instead?  You
  591.   can use a MS-DOG hard disk partition or DOG-format diskettes to store
  592.   the files.  The archives also begin with the letters tb, td, or tm,
  593.   and so on, which is the implementors' shorthand for TeX binary, TeX
  594.   documentation, TeX macro, and so on.  The difference to you is
  595.   academic, because you'll be installing everything anyway.
  596.  
  597.   Simply fire up the Slackware install utility.  You needn't concern
  598.   yourself with reconfiguring the system, so select the option to add
  599.   new software.  Select the appropriate source media (diskettes, HD
  600.   partition, or CD-ROM), specify that you want to install the Slackware
  601.   t series, and that you do not want to be prompted -- simply install
  602.   all the archives on the Slackware t series diskettes.  You'll be
  603.   prompted to insert each diskette in the floppy drive if you're
  604.   installing from diskettes.  If you're installing from a hard drive or
  605.   CD-ROM, no more intervention is required by you.
  606.  
  607.   3.2.1.1.  Manual Slackware install.
  608.  
  609.   This section is for people who, for one reason or another, would like
  610.   to install teTeX manually from a Linux package.
  611.  
  612.   Let's assume that you've assembled the Slackware teTeX distribution on
  613.   floppy diskettes labelled t1 thru t9. Mount the t1 diskette like this
  614.  
  615.   mount /dev/fd0 /mnt
  616.  
  617.   if your Linux configuration is a standard configuration.  Actually,
  618.   any mount point will do.  You'll simply need to substitute the appro¡
  619.   priate path spec in the next few steps.
  620.  
  621.   The next thing you want to do is create the teTeX top-level directory.
  622.   teTeX's internal paths are specified relative to its binary program
  623.   files, but the Slackware distribution is archived relative to the root
  624.   directory.  So the top-level teTeX directory is:
  625.  
  626.   /usr/lib/teTeX
  627.  
  628.   For each of the .tgz archive files in the distribution, copy the
  629.   archive file to the /usr/lib/teTeX directory and repeat the following
  630.   commands:
  631.  
  632.   You should be logged in as root and in the top-level directory, /, for
  633.   these steps.  I've used the tb-xfig.tgz archive for demonstration
  634.   purposes.  Of course, you'll want to substitute the name of whichever
  635.   archive you're unpacking.
  636.  
  637.   cp /mnt/tb-xfig.tgz /usr/lib/teTeX
  638.   tar -zxvf /usr/lib/teTeX/tb-xfig.tar  # v to see what's going on!
  639.   rm /usr/lib/teTeX/tb-xfig.tgz
  640.  
  641.   Most Slackware packages that I've seen also include an install script,
  642.   which the Slackware installer executes after unpacking the files.
  643.   Look in the directory /install after you've unpacked the files.  If
  644.   there's a script there called doinst.sh, execute that, as root, by
  645.   typing
  646.  
  647.   sh < /install/doinst.sh
  648.  
  649.   It may be alarming to watch all those filenames scrolling of the top
  650.   of the screen as the archives are unpacked.  Relax!  Take a break, and
  651.   freshen up your coffee (or grab another JOLT from the refrigerator, or
  652.   otherwise replenish whatever you're drinking).  There's only a few
  653.   more steps you need to perform to install teTeX.  They're covered in
  654.   Section 4.
  655.  
  656.   3.2.2.  Debian GNU/Linux, V. 1.3.
  657.  
  658.   Installing teTeX from Debian packages is truly trivial.  ftp the most
  659.   recent stable versions of the teTeX archive files from ftp.debian.org.
  660.   The teTeX distribution is located in the directory
  661.  
  662.   pub/debian/bo/binary-i386/tex
  663.  
  664.   Retrieve the following Debian archive files via anonymous FTP (remem¡
  665.   bering to set binary mode for the transfers).
  666.  
  667.   tetex-base_0.4pl6-5.deb
  668.   tetex-bin_0.4pl6-8.deb
  669.   tetex-dev_0.4pl6-8.deb
  670.   tetex-doc_0.4pl6-1.deb
  671.   tetex-extra_0.4pl6-4.deb
  672.  
  673.   Once the files are safely transferred to your local hard disk, su to
  674.   root, and install them using the dpkg(1) utility:
  675.  
  676.   dpkg -i tetex-base_0.4pl6-5.deb
  677.   dpkg -i tetex-bin_0.4pl6-8.deb
  678.   dpkg -i tetex-dev_0.4pl6-8.deb
  679.   dpkg -i tetex-doc_0.4pl6-1.deb
  680.   dpkg -i tetex-extra_0.4pl6-4.deb
  681.  
  682.   Installation will take some time, because the Debian archives contain
  683.   the shell scripts necessary to check for old TeX installations, build
  684.   the TeX and LaTeX .fmt files, build the path-searching database, and
  685.   see to other configuration details.  However, once they are finished,
  686.   you should have an operational teTeX installation that needs only to
  687.   be configured for the details of your local system; see section
  688.   ``Post-installation configuration details''.
  689.  
  690.   3.2.3.  RedHat V. 4.2.
  691.  
  692.   Presumably, you could install only selected portions of the teTeX
  693.   RedHat distribution, but consistent with the philosophy of the other
  694.   sections, it is assumed that you will eventually need all of the
  695.   facilities provided by teTeX, and so you should install the complete
  696.   distribution.
  697.  
  698.   To install teTeX from RedHat Linux RPM packages, under RedHat Linux v.
  699.   4.2, ftpto sunsite.unc.edu and cd to the directory
  700.  
  701.   pub/Linux/distributions/redhat/current/i386/RedHat/RPMS/
  702.  
  703.   Set binary mode for the transfers and retrieve the following files:
  704.  
  705.   tetex-0.4pl8-5.i386.rpm
  706.   tetex-latex-0.4pl8-5.i386.rpm
  707.   tetex-afm-0.4pl8-5.i38 6.rpm
  708.   tetex-dvilj-0.4pl8-5.i386.rpm
  709.   tetex-dvips-0.4pl8-5.i386.rpm
  710.   tetex-xdvi-0.4pl8-5.i386.rpm
  711.   tetex-texmf-src-0.4pl8-5.i386.rpm
  712.  
  713.   This last file may not be strictly necessary.  It contains the LaTeX
  714.   sources, if you want to install LaTeX yourself.  If you're thinking of
  715.   upgrading LaTeX independently of the binaries in the future, this
  716.   archive could be useful to have around:
  717.  
  718.   Simply install the files above in the order given, using the rpm -i
  719.   command, and proceed to the section, ``Post-installation configuration
  720.   details''.
  721.  
  722.   3.3.  Ghostscript V. 5.03.
  723.  
  724.   Ghostscript development is rapid, and the changes which are
  725.   incorporated into every new version are significant.  Therefore, it's
  726.   worth the effort to install the version of Ghostscript that is
  727.   available on its home page, http://www.cs.wisc.edu/~ghost.
  728.  
  729.   At the time of this writing, the current version is 5.03.  The
  730.   Ghostscript archive for Linux is composed of the following files:
  731.  
  732.   ghostscript-5.03gnu.tar.gz
  733.   ghostscript-5.03jpeg.tar.gz
  734.   ghostscript-5.03libpng.tar.gz
  735.   ghostscript-5.03zlib.tar.gz
  736.   ghostscript-fonts-std-5.03.tar.gz
  737.   ghostscript-fonts-other-5.03.tar.gz
  738.  
  739.   What is Ghostscript, and why do you need it?  Technically, Ghostscript
  740.   is a Raster Image Processor.  It translates PostScript code into many
  741.   common, bit-mapped formats, like those understood by your printer or
  742.   screen, whether or not they are equipped with PostScript.  In
  743.   practical terms, Ghostscript allows you to use Type 1 fonts, and mix
  744.   text and graphics on any printer or video display that Ghostscript
  745.   knows about.
  746.  
  747.   The quality of the fonts which come with the program have improved
  748.   steadily in the last several versions as well.  Or maybe it's that
  749.   more recent versions of Ghostscript have improved font rendering.  In
  750.   either case, this is of real benefit for Linux users, who may not be
  751.   able to spend hundreds of dollars on commercial fonts.  Because
  752.   Ghostscript is able to read the font requests made by dvips(1),
  753.   Ghostscript's font library provides the fonts, not teTeX.  But the
  754.   font metrics files for Ghostscript's font library, which have the
  755.   extension .afm, are already included in the teTeX distribution.
  756.  
  757.   For information about using Ghostscript, see the file use.txt in the
  758.   Ghostscript distribution, and the Linux Documentation Project's
  759.   Printing-HOWTO.  There's also a Ghostscript manual available from the
  760.   Internet.  See section ``Resources for further information''
  761.  
  762.   Or, install APSFILTER and let that run Ghostscript automatically.
  763.   (See section ``APSFILTER'').
  764.  
  765.   A final, significant note: I would recommend that you compile
  766.   Ghostscript for your own system, if possible.  Combining different
  767.   versions of Ghostscript and svgalib can quickly become confusing.  The
  768.   version of Ghostscript which is included in the Slackware AP set is
  769.   version 2.6.2 and does not have X support compiled in.  You might also
  770.   have trouble finding the correct svgalib versions for it.  There is
  771.   supposedly a version of Ghostscript with X11 support in the Slackware
  772.   XAP distribution series, and presumably in the other Linux
  773.   distributions, though I haven't tried them.  Compiling Ghostscript for
  774.   your own system is far easier, it seems to me.
  775.  
  776.   It's also important to remember that there are two Ghostscript
  777.   releases in distribution: the commercial, Aladdin Ghostscript, and GNU
  778.   Ghostscript, which lags behind Aladdin Ghostscript by several years.
  779.   This is due to Ghostscript's unique licensing arrangement.  See the
  780.   Printing-HOWTO for more information about Ghostscript licensing.
  781.  
  782.   svgalib support for GNU Ghostscript 3.33 is included in a small
  783.   archive which contains a .diff file.  Ghostscript 3.33 for X is also
  784.   configured for JPEG support, so you should include the JPEG library
  785.   sources as well.  The relevant archives can be found at any GNU
  786.   distribution site, like ftp://prep.ai.mit.edu/pub/gnu.
  787.  
  788.   3.4.  APSFILTER.
  789.  
  790.   There are software packages which will simplify your life, and
  791.   APSFILTER is one of them.  Written by Andreas Klemm, APSFILTER works
  792.   with any BSD-compatible printer daemon (which means that you have the
  793.   lpd(8) program and an /etc/printcap file; see below), and provides
  794.   transparent printer support for ASCII, DVI, and PostScript files, as
  795.   well as files compressed by gzip(1), compress(1), and other data
  796.   compression software.
  797.  
  798.   Once you have successfully installed APSFILTER, you can print a
  799.   PostScript file to whatever printer you have, by typing
  800.  
  801.   lpr file.ps
  802.  
  803.   Or, to print an ASCII file without PostScript translation, you can
  804.   type
  805.  
  806.   lpr -Praw file.asc
  807.  
  808.   Amazing.
  809.  
  810.   APSFILTER is surprisingly easy to install, considering that it works
  811.   with many disparate elements of your system.  Installing the generic
  812.   APSFILTER distribution, however, does require that you have a current
  813.   gcc(1) compiler on hand, because APSFILTER builds some of its filters
  814.   during installation.  Some distributions of Linux, however, provide a
  815.   pre-built version, so check your specific distribution first.
  816.  
  817.   In any event, you will need a correctly installed Ghostscript and
  818.   lpd(8) installation for APSFILTER to work.  The most recent APSFILTER
  819.   is located in the Linux Archives at
  820.   ftp://sunsite.unc.edu/pub/Linux/system/printing/.
  821.  
  822.   3.5.  The lpd(8) daemon.
  823.  
  824.   There are wide variations in printers and configurations.  Setting up
  825.   a working printer daemon is no mean feat.  If you're using teTeX on an
  826.   individual system, you could simply dump the output to the printer
  827.   device driver file, but this is less than desirable.  You lose the
  828.   filtering capabilities of the printer daemon.  If you're printing on a
  829.   network, having a working printer daemon is a must.
  830.  
  831.   The basic UNIX program for printer management on BSD-style systems is
  832.   lpd(8).  When you print a file with lpr(1) you are really sending the
  833.   file to a print queue.  lpd(8) prints files in the order they're
  834.   queued.  Other printer utilities include lpq(1), which displays the
  835.   contents of the print queue, and lprm(1), which removes (dequeues)
  836.   files from the print queue.
  837.  
  838.   The printer daemon can perform other tasks, like transparently
  839.   filtering output from various programs (using filter programs like
  840.   APSFILTER, above), accept print jobs from other machines on a network,
  841.   send print jobs to various printers if you have more than one
  842.   connected, and hold print output until you've refilled the paper feed
  843.   tray.
  844.  
  845.   The Printing-HOWTO explains the process of setting up a working
  846.   printer daemon in detail.  Many Linux distributions already have
  847.   configured lpd(8) suites.  Check there first, because it will save you
  848.   considerable work.  They're usually archived, strangely enough, using
  849.   the name lpr, so search for that program.  There is also a printer
  850.   daemon suite available from the Linux archives, at
  851.   ftp://sunsite.unc.edu/pub/Linux/system/printing.
  852.  
  853.   4.  Post-installation configuration details.
  854.  
  855.   The first thing you'll want to do is look at Thomas Esser's README
  856.   file.  It contains a lot of hints on how to configure teTeX for your
  857.   output device (i.e., printer).  The README file is located in the
  858.   directory
  859.  
  860.   /usr/lib/teTeX/texmf/doc/tetex
  861.  
  862.   Read the file over with the command (the path in the following exam¡
  863.   ples is that of the Slackware distribution):
  864.  
  865.   less /usr/lib/teTeX/texmf/doc/tetex/README
  866.  
  867.   or, print it out with the command
  868.  
  869.   cat /usr/lib/teTeX/texmf/doc/tetex/README >/dev/lp0
  870.  
  871.   assuming that your printer is connected to /dev/lp0.  Substitute the
  872.   device driver file that your printer is connected to, as appropriate.
  873.  
  874.   Or, better still, print it using the lpr(1) command:
  875.  
  876.   lpr /usr/lib/teTeX/texmf/doc/tetex/README
  877.  
  878.   You should have installed the printer daemon that is included with
  879.   your distribution of Linux.  If not, do that now, per the instructions
  880.   that come with the package.  If you don't have one of the packages, or
  881.   want to install a printer daemon yourself, see section ``The lpd(8)
  882.   daemon''
  883.  
  884.   Print out the teTeX-FAQ. Keep the FAQ handy because it contains useful
  885.   hints for configuring teTeX's output drivers for your printer.  We'll
  886.   get to that in a moment.  In more recent releases of teTeX, the teTeX-
  887.   FAQ is viewable via the texconfig utility.
  888.  
  889.   Next, you want to define a directory to store your own TeX format
  890.   files.  teTeX searches the directories listed by the $TEXINPUTS
  891.   environment variable for local TeX input files.  On Chanel3, I added
  892.   the line
  893.  
  894.   export TEXINPUTS=".:~/texinputs:"
  895.  
  896.   to the system-wide /etc/profile file.  Individual users can set their
  897.   own local $TEXINPUTS directory, by adding the line in their ~/.profile
  898.   or ~/.bash_profile if bash(1) is the default shell.  The $TEXINPUTS
  899.   environment variable tells teTeX to look for users' individual TeX
  900.   style files in the ~/texinputs directories under each user's home
  901.   directory.  It is critical that a colon appear before and after this
  902.   directory.  teTeX is going to append its own directory searches to
  903.   your own.  You want to have teTeX search the local format files first,
  904.   so it uses the local versions of any of the standard files you have
  905.   edited.
  906.  
  907.   Add the /usr/lib/teTeX/bin directory to the system-wide path if you're
  908.   installing teTeX as root.  Again, if you're installing a personal copy
  909.   of teTeX, add the directory where the teTeX binaries are located to
  910.   the front your $PATH with the following line in your ~/.profile or
  911.   ~/.bash_profile:
  912.  
  913.   export PATH="~/tetex/bin:"$PATH
  914.  
  915.   Now, log in as root and run texconfig per the instructions in the
  916.   teTeX-FAQ and choose the printer that is attached to your system.
  917.   Make sure that you configure teTeX for both the correct printer and
  918.   printer resolution.
  919.  
  920.   Finally, run the texhash program.  This ensures that teTeX's internal
  921.   database is up to date.  The database is actually a ls-lR file.  You
  922.   must run texhash every time you change the system configuration, or
  923.   teTeX will not be able to locate your changes.
  924.  
  925.   4.1.  What if my printer isn't included?
  926.  
  927.   The teTeX distribution comes with only a limited selection of DVI
  928.   output drivers: dvips(1), drivers for Hewlett Packard LaserJets, and
  929.   nothing else.  You have two options if you have a printer which isn't
  930.   LaserJet-compatible: You can use dvips(1) and Ghostscript, which I
  931.   would recommend anyway, for reasons already mentioned, or you can
  932.   investigate other dviware sources.
  933.  
  934.   A limited number of DVI drivers have been ported to Linux and are
  935.   available as pre-built binaries.  They are located in the Linux
  936.   archives at ftp://sunsite.unc.edu/pub/Linux/apps/tex/dvi/.
  937.  
  938.   The master dviware libraries are maintained at the University of Utah
  939.   archives.  If you can't find a DVI driver there that supports your
  940.   printer, chances are that it doesn't exist.  You can also write your
  941.   own DVI driver using the templates available there.  The library's URL
  942.   is ftp://ftp.math.utah.edu/pub/tex/dvi/.
  943.  
  944.   5.  Using teTeX.
  945.  
  946.   Theoretically, at least, everything is installed correctly and is
  947.   ready to run.  teTeX is a very large software package.  As with any
  948.   complex software package, you'll want to start by learning teTeX
  949.   slowly, instead of being overwhelmed by its complexity.
  950.  
  951.   At the same time, we want the software to do something useful.  So
  952.   instead of watching TeX typeset
  953.  
  954.   ``Hello, World!''
  955.  
  956.   as Professor Knuth suggests in the The TeXBook, we'll produce a couple
  957.   of teTeX's own documents in order to test it.
  958.  
  959.   The next section, ``Printing the documentation'', is really a tutorial
  960.   for operating teTeX.  It covers printing the documentation included
  961.   with teTeX (which is in LaTeX and ``cookbook'' than a tutorial.  It
  962.   discusses how to format LaTeX documents, and covers a few of the
  963.   commands and environments of the more commonly used document classes.
  964.  
  965.   The section ``LaTeX extension packages and other resources'' tells how
  966.   to use the many pre-existing LaTeX packages to customize documents to
  967.   your specifications.
  968.  
  969.   5.1.  Printing the documentation.
  970.  
  971.   You should be logged in as root the first few times you run teTeX.  If
  972.   you aren't, metafont may not be able to create the necessary
  973.   directories for its fonts.  The texconfig program includes an option
  974.   to make the font directories world-writable, but if you're working on
  975.   a multi-user system, security considerations may make this option
  976.   impractical or undesirable.
  977.  
  978.   In either instance, if you don't have the appropriate permissions to
  979.   write to the directories where the fonts are stored, metafont will
  980.   complain loudly because it can't make the directories.  You won't see
  981.   any output because you have a bunch of zero-length font characters.
  982.   This is no problem.  Simply log out, re-login as root, and repeat the
  983.   offending operation.
  984.  
  985.   The nice thing about teTeX is that, if you blow it, no real harm is
  986.   done.  It's not like a compiler, where, say, you will trash the root
  987.   partition if a pointer goes astray.  What, you haven't read the teTeX
  988.   manual yet?  Of course you haven't.  It's still in the distribution,
  989.   in source code form, waiting to be output.
  990.  
  991.   So, without further delay, you will want to read the teTeX manual.
  992.   It's located in the directory
  993.  
  994.   /usr/lib/teTeX/texmf/doc/tetex.
  995.  
  996.   The LaTeX source for the manual is called TETEXDOC.tex.  (The editors,
  997.   like emacs(1), can tell the difference.)  There is also a file
  998.   TETEXDOC.dvi included with the distribution, which you might want to
  999.   keep in a safe place---say, another directory ---in case you want to
  1000.   test your .dvi drivers later.  With that out of the way, type
  1001.  
  1002.   latex TETEXDOC.tex
  1003.  
  1004.   LaTeX will print several warnings.  The first,
  1005.  
  1006.   LaTeX Warning: Label(s) may have changed. Rerun to get the
  1007.   cross-references right.
  1008.  
  1009.   is standard.  It's common to build a document's Table of Contents by
  1010.   LaTeXing the document twice.  So, repeat the command.  The other warn¡
  1011.   ings can be safely ignored.  They simply are informing you that some
  1012.   of the FTP paths mentioned in the documentation are too wide for their
  1013.   alloted spaces.  (If you're really inquisitive, look at one of the TeX
  1014.   references for a discussion of \hbox and \vbox.)
  1015.  
  1016.   teTeX will have generated several files from TETEXDOC.tex.  The one
  1017.   that we're interested in is TETEXDOC.dvi. This is the device-
  1018.   independent output which you can send either to the screen or the
  1019.   printer.  If you're running teTeX under the X Windows System, you can
  1020.   preview the document with xdvi(1).
  1021.  
  1022.   For the present, let's assume that you have a HP LaserJet II.  You
  1023.   would give the command
  1024.  
  1025.   dvilj2 TETEXDOC.dvi
  1026.  
  1027.   which will write a PCL output file from TETEXDOC.dvi, including soft
  1028.   fonts which will be downloaded to the LaserJet.  This is not a feature
  1029.   of TeX or LaTeX, but a feature provided by dvilj2(1). Other .dvi
  1030.   drivers provide features which are relevant to the devices they sup¡
  1031.   port.  dvilj2(1) will fill the font requests which were made in the
  1032.   original LaTeX document with the the closest equivalents available on
  1033.   the system.  In the case of a plain-text document like TETEXDOC.tex,
  1034.   there isn't much difficulty.  All of the fonts requested by TETEX¡
  1035.   DOC.tex will be generated by metafont, which is automatically invoked
  1036.   by dvilj2(1) and generates the fonts if they aren't already present.
  1037.   (If you're running dvilj2(1) for the first time, the program needs to
  1038.   generate all of the fonts, which could take up to several days if
  1039.   you're using a really slow machine.)  There are several options which
  1040.   control font generation via dvilj2(1); they're outlined in the manual
  1041.   page.  At this point, you shouldn't need to operate metafont directly.
  1042.   If you do, then something has gone awry with your installation.  All
  1043.   of the .dvi drivers will invoke metafont directly via the kpathsea
  1044.   path-searching library---also beyond the scope of this document---and
  1045.   you don't need to do any more work with metafont for the present---all
  1046.   of the metafont sources for the Computer Modern font library are pro¡
  1047.   vided.
  1048.  
  1049.   You can print TETEXDOC.lj with the command
  1050.  
  1051.   lpr TETEXDOC.lj
  1052.  
  1053.   You may need to install a printer filter that understands PCL.  Look
  1054.   at the Printing-HOWTO for details.
  1055.  
  1056.   The nine-page teTeX Guide provides some useful information for further
  1057.   configuring your system, some of which I have mentioned, much which
  1058.   this document doesn't cover.
  1059.  
  1060.   Some of the information in the next section I haven't been able to
  1061.   test, because I have a non-PostScript HP Deskjet 400 color ink jet
  1062.   printer connected to Chanel3's parallel port.  However, not owning a
  1063.   PostScript printer is no barrier to printing text and graphics from
  1064.   your text documents.  See the section ``Ghostscript'' to install
  1065.   Ghostscript, if it isn't already installed on your system.
  1066.  
  1067.   5.2.  TeX and LaTeX commands.
  1068.  
  1069.   5.2.1.  Document structure.
  1070.  
  1071.   Preparing documents for TeX typesetting is easy.  Make sure there's a
  1072.   blank line between the paragraphs of a plain text file, and run file
  1073.   through the TeX program with the command
  1074.  
  1075.   TeX your_text_file
  1076.  
  1077.   The result will be a file of the same base name and the extension sin¡
  1078.   gle-spaced, with justified left and right margins.  If you receive
  1079.   error messages from special characters like dollar signs, escape them
  1080.   with a backslash character, \, and run TeX on the file again.  You
  1081.   should be able to process the resulting file with the printed output.
  1082.  
  1083.   The only other peculiarity of TeX input files is to make sure that you
  1084.   use opening and closing quotes, which are denoted in the input file
  1085.   with the grave accent and single quote characters.  Emacs' TeX mode
  1086.   will do this for you automatically.
  1087.  
  1088.   "These are ascii-type quotes."
  1089.   ``These are `TeX-style' quotes.''
  1090.  
  1091.   You can consult a guide like A Gentle Introduction to TeX, described
  1092.   above, for hints on how to make modifications to the default TeX page
  1093.   format.
  1094.  
  1095.   Documents formatted for LaTeX have a few more rules, but with complex
  1096.   documents, LaTeX can greatly simplify the formatting process.
  1097.  
  1098.   Essentially, LaTeX is a document markup language which tries to
  1099.   separate the output style from the document's logical content.  For
  1100.   example, formatting a section heading with TeX would require
  1101.   specifying 36 points of white space above the heading, then the
  1102.   heading itself set in bold, 24-point type, then copying the heading
  1103.   text and page number to the Table of Contents, then leaving 24 points
  1104.   of white space after the heading.  By contrast, LaTeX has the
  1105.   \section{} command, which does all of the work for you.  If you need
  1106.   to change the format of the section headings throughout your document,
  1107.   you can change the definition of \section{} instead of the text in the
  1108.   document.  You can see where this would save hours of reformatting for
  1109.   documents of more than a dozen pages in length.
  1110.   All LaTeX documents have three sections: a preamble, the body text,
  1111.   and a postamble.  These terms are standard jargon and are widely used
  1112.   by TeXperts.
  1113.  
  1114.   The preamble, at a minimum, specifies the type of document to be
  1115.   produced---the document class---and a statement which signals the
  1116.   beginning of the document's body text.  For example:
  1117.  
  1118.   \documentclass{article}
  1119.   \begin{document}
  1120.  
  1121.   The document's postamble is usually very simple.  Except in special¡
  1122.   ized cases, it contains only the statement:
  1123.  
  1124.   \end{document}
  1125.  
  1126.   Note the \begin{document} and \end{document} pairing.  In LaTeX, this
  1127.   is called an environment.  All text must appear within an environment,
  1128.   and many commands are effective only in the environments in which
  1129.   they're called.  The document environment is the only instance where
  1130.   LaTeX enforces this convention, however.  That is, it's the only envi¡
  1131.   ronment that is required in a document.  (An exception is letter
  1132.   class, which also requires you to declare \begin{letter} and
  1133.   \end{letter}.  See the section ``Letters''.)  However, many formatting
  1134.   features are specified as environments.  They're described in the fol¡
  1135.   lowing sections.
  1136.  
  1137.   The document classes can be called with arguments.  For example,
  1138.   instead of the default, 10-point type used as the base point size, as
  1139.   in the previous example, we could have specified
  1140.  
  1141.   \documentclass[12pt]{article}
  1142.  
  1143.   to produce the document using 12 points as the base point size.  The
  1144.   document class, article, makes the necessary adjustments.
  1145.  
  1146.   There are a few document classes which are commonly used.  They're
  1147.   described below.  The report class is similar to article class, but
  1148.   produces a title page and starts each section on a new page.  The
  1149.   letter class includes special definitions for addresses, salutations,
  1150.   and closings, a few of which are described below.
  1151.  
  1152.   You can include canned LaTeX code, commonly known as a package, with
  1153.   the \usepackage{} command.
  1154.  
  1155.   \usepackage{fancyhdr}
  1156.  
  1157.   The command above would include the LaTeX style file fancyhdr.sty from
  1158.   one of the TEXINPUTS directories, which you and teTeX specified during
  1159.   installation and setup processes.
  1160.  
  1161.   \documentclass{article}
  1162.   \usepackage{fancyhdr}
  1163.   \begin{document}
  1164.  
  1165.   Note that the \usepackage{} declarations are given before the
  1166.   \begin{document} statement; that is, in the document preamble.
  1167.  
  1168.   fancyhdr.sty extends the \pagestyle{} command so that you can create
  1169.   custom headers and footers.  Most LaTeX document classes provide
  1170.   headers and footers of the following standard page styles:
  1171.  
  1172.   \pagestyle{plain}       % default pages style -- page number centered at
  1173.                           % the bottom of the page.
  1174.   \pagestyle{empty}       % no headers or footers
  1175.   \pagestyle{headings}    % print section number and page number at the
  1176.                           % top of the page.
  1177.   \pagestyle{myheadings}  % print custom information in the page heading.
  1178.  
  1179.   Everything on a line to the right of the percent sign is a comment.
  1180.  
  1181.   The \pagestyle{} command doesn't take effect until the following page.
  1182.   To change the headers and footers on the current page, use the command
  1183.  
  1184.   \thispagestyle{the_pagestyle}
  1185.  
  1186.   5.2.2.  Characters and type styles.
  1187.  
  1188.   Character styles are partially a function of the fonts specified in
  1189.   the document.  However, bold and italic character emphasis should be
  1190.   available for every font present on the system.  Underlining, too, can
  1191.   be used, though its formatting presents special problems.  See section
  1192.   ``LaTeX extension packages and other resources'', below.
  1193.  
  1194.   You can specify text to be emphasized in several ways.  The most
  1195.   portable is the \em command.  All text within its scope is italicized
  1196.   by default.  For example:
  1197.  
  1198.   This word will be {\em emphasized.}
  1199.  
  1200.   If you have italicized text that runs into text which is not itali¡
  1201.   cized, you can specify an italic correction factor to be used.  The
  1202.   command for this is \/; that is, a backslash and a forward slash.
  1203.  
  1204.   This example {\em will\/} print correctly.
  1205.  
  1206.   This example will {\em not} print correctly.
  1207.  
  1208.   Slightly less portable, but still acceptable in situations where
  1209.   they're used singly, are the commands \it, \bf, and \tt, which specify
  1210.   that the characters within their scope be printed using italic, bold,
  1211.   and monospaced (teletype) typefaces, respectively.
  1212.  
  1213.   {\tt This text will be printed monospaced,}
  1214.   {\it this text will be italic,} and
  1215.   {\bf this text will be bold\dots} all in one paragraph.
  1216.  
  1217.   The command \dots prints a series of three periods for ellipses, which
  1218.   will not break across a line.
  1219.  
  1220.   The most recent version of LaTeX, which is what you have, includes
  1221.   commands which account for instances where one emphasis command would
  1222.   supersede another.
  1223.  
  1224.   This is {\it not {\bf bold italic!}}
  1225.  
  1226.   What happens is that teTeX formats the text with the italic typeface
  1227.   until it encounters the \bf command, at which point it switches to
  1228.   boldface type.
  1229.  
  1230.   To get around this, the NFSS scheme of selecting font shapes requires
  1231.   three parameters for each typeface: shape, series, and family.  Not
  1232.   all font sets will include all of these styles.  LaTeX will print a
  1233.   warning, however, if it needs to substitute another font.
  1234.  
  1235.   You can specify the following font shapes:
  1236.  
  1237.   \textup{text}           % upright shape (the default)
  1238.   \textit{text}           % italic
  1239.   \textsl{text}           % slanted
  1240.   \textsc{text}           % small caps
  1241.  
  1242.   These are the two series that most fonts have:
  1243.  
  1244.   \textmd{text}           % medium series (the default)
  1245.   \textbf{text}           % boldface series.
  1246.  
  1247.   There are generally three families of type available.
  1248.  
  1249.   \textrm{text}           % roman (the default)
  1250.   \textsf{text}           % sans serif
  1251.   \texttt{text}           % typewriter (monospaced, Courier-like)
  1252.  
  1253.   Setting font styles using these parameters, you can combine effects.
  1254.  
  1255.   \texttt{\textit{This example likely will result in a font
  1256.   substitution, because many fonts don't include a typewriter italic
  1257.   typeface.}}
  1258.  
  1259.   The font family defaults to Computer Modern, which is a bit-mapped
  1260.   font.  Other font families are usually PostScript-format Type 1 fonts.
  1261.   See section ``Using PostScript fonts'' for details on how to specify
  1262.   them.
  1263.  
  1264.   There are also many forms of accents and special characters which are
  1265.   available for typesetting.  This is only a few of them.  (Try
  1266.   typesetting these on your own printer.)
  1267.  
  1268.   \'{o}   \`{e}   \^{o}   \"{u}   \={o}   \c{c}   `? `!
  1269.   \copyright      \pounds         \dag
  1270.  
  1271.   Finally, there are characters which are used as meta- or escape char¡
  1272.   acters in TeX and LaTeX.  One of them, the dollar sign, is mentioned
  1273.   above.  The complete set of metacharacters, which need to be escaped
  1274.   with a backslash to be used literally, is:
  1275.  
  1276.   # $ % & _ { }
  1277.  
  1278.   There are also different alphabets available, like Greek and Cyrillic.
  1279.   LaTeX provides many facilities for setting non-English text, which are
  1280.   covered by some of the other references mentioned here
  1281.  
  1282.   5.2.3.  Margins and line spacing.
  1283.  
  1284.   Changing margins in a TeX or LaTeX document is not a straightforward
  1285.   task.  A lot depends on the relative indent of the text you're trying
  1286.   to adjust the margin for.  The placement of the margin-changing
  1287.   command is also significant.
  1288.  
  1289.   For document-wide changes to LaTeX documents, the \evensidemargin and
  1290.   \oddsidemargin commands are available.  They affect the left-hand
  1291.   margins of the even-numbered and odd-numbered pages, respectively.
  1292.   For example,
  1293.  
  1294.   \evensidemargin=1in
  1295.   \oddsidemargin=1in
  1296.  
  1297.   adds on inch to the left-hand margin of the even and odd pages in
  1298.   addition to the standard one-inch, left-hand margin.  These commands
  1299.   affect the entire document and will shift the entire body of the text
  1300.   right and left across a page, regardless of any local indent, so
  1301.   they're safe to use with LaTeX environments like verse and list.
  1302.  
  1303.   Below is a set of margin-changing macros which I wrote.  They have a
  1304.   different effect than the commands mentioned above.  Because they use
  1305.   plain TeX commands, they're not guaranteed to honor the margins of any
  1306.   LaTeX environments which may be in effect, but you can place them
  1307.   anywhere in a document and change the margins from that point on.
  1308.  
  1309.   %%  margins.sty -- v. 0.1   by Robert Kiesling
  1310.   %%  Copies of this code may be freely distributed in verbatim form.
  1311.   %%
  1312.   %%  Some elementary plain TeX margin-changing commands. Lengths are
  1313.   %%  in inches:
  1314.   %%  \leftmargin{1}   %% sets the document's left margin in 1 inch.
  1315.   %%  \leftindent{1}   %% sets the following paragraphs' indent in
  1316.   %%                     1 inch.
  1317.   %%  \rightindent{1}  %% sets the following paragraphs' right margins
  1318.   %%                   %% in 1 inch.
  1319.   %%  \llength{3}      %% sets the following lines' lengths to 3 inches.
  1320.   %%
  1321.   \message{Margins macros...}
  1322.   \def\lmargin#1{\hoffset = #1 in}
  1323.   \def\lindent#1{\leftskip = #1 in}
  1324.   \def\rindent#1{\rightskip = #1 in}
  1325.   \def\llength#1{\hsize = #1 in}
  1326.   %%
  1327.   %% (End of margins macros.}
  1328.  
  1329.   Place this code in a file called margins.sty in your local $TEXINPUTS
  1330.   directory.  The commands are explained in the commented section of the
  1331.   file.  To include them in a document, use the command
  1332.  
  1333.   \usepackage{margins}
  1334.  
  1335.   in the document preamble.
  1336.  
  1337.   While we're on the subject, if you don't want the right margin to be
  1338.   justified, which is the default, you can tell LaTeX to use ragged
  1339.   right margins by giving the command:
  1340.  
  1341.   \raggedright
  1342.  
  1343.   Setting line spacing also has its complexities.
  1344.  
  1345.   The baselineskip measurement is the distance between lines of text.
  1346.   It is given as an absolute measurement.  For example,
  1347.  
  1348.   \baselineskip=24pt
  1349.  
  1350.   or even better:
  1351.  
  1352.   \setlength{\baselineskip}{24pt}
  1353.  
  1354.   The difference between the two forms is that setlength will respect
  1355.   any scoping rules that may be in effect when you use the command.
  1356.  
  1357.   The problem with using baselineskip is that it also affects the
  1358.   distance between section headings, footnotes, and the like.  You need
  1359.   to take care that baselineskip is correct for whatever text elements
  1360.   you're formatting.  There are, however, LaTeX macro packages, like
  1361.   setspace.sty, which will help you in these circumstances.  See section
  1362.   ``LaTeX extension packages and other resources''.
  1363.  
  1364.   5.2.4.  Document classes.
  1365.  
  1366.   LaTeX provides document classes which provide standardized formats for
  1367.   documents.  They provide environments to format lists, quotations,
  1368.   footnotes, and other text elements.  Commonly used document classes
  1369.   are covered in the following sections.
  1370.  
  1371.   5.2.4.1.  Articles and reports.
  1372.  
  1373.   As mentioned above, the article class and the report class are
  1374.   similar.  The main differences are that the report class creates a
  1375.   title page by default and begins each section on a new page.  Mostly,
  1376.   though, the two document classes are similar.
  1377.  
  1378.   To create titles, abstracts, and bylines in these document classes,
  1379.   you can type, for example,
  1380.  
  1381.   \title{The Breeding Habits of Cacti}
  1382.   \author{John Q. Public}
  1383.   \abstract{Description of how common desert cacti search
  1384.   for appropriate watering holes to perform their breeding
  1385.   rituals.}
  1386.  
  1387.   in the document preamble.  Then, the command
  1388.  
  1389.   \maketitle
  1390.  
  1391.   given at the start of the text, will generate either a title page in
  1392.   the report class, or the title and abstract at the top of the first
  1393.   page, in the article class.
  1394.  
  1395.   Sections can be defined with commands that include the following:
  1396.  
  1397.   \section
  1398.   \subsection
  1399.   \subsubsection
  1400.  
  1401.   These commands will produce the standard, numbered sections used in
  1402.   technical documents.  For unnumbered sections, use
  1403.  
  1404.   \section*
  1405.   \subsection*
  1406.   \subsubsection*
  1407.  
  1408.   and so on.
  1409.  
  1410.   LaTeX provides many environments for formatting displayed material.
  1411.   You can include quoted text with the quotation environment.
  1412.  
  1413.   \begin{quotation}
  1414.   Start of paragraph to be quoted...
  1415.  
  1416.   \end{quotation}
  1417.  
  1418.   For shorter quotes, you can use the quote environment.
  1419.  
  1420.   To format verse, use the verse environment.
  1421.  
  1422.   \begin{verse}
  1423.   Because I could not stop for death\\
  1424.   He kindly stopped for me
  1425.   \end{verse}
  1426.  
  1427.   Notice that you must use the double backslashes to break lines in the
  1428.   correct places.  Otherwise, LaTeX fills the lines in a verse environ¡
  1429.   ment, just like any other environment.
  1430.  
  1431.   Lists come in several flavors.  To format a bulleted list, the list
  1432.   environment is used:
  1433.  
  1434.   \begin{list}
  1435.   \item
  1436.   This is the first item of the list.
  1437.   \item
  1438.   This is the second item of the list...
  1439.   \item
  1440.   \end{list}
  1441.  
  1442.   A numbered list uses the enumerate environment:
  1443.  
  1444.   \begin{enumerate}
  1445.   \item
  1446.   Item No. 1.
  1447.   \item
  1448.   Item No. 2.
  1449.   \item
  1450.   \dots
  1451.   \end{enumerate}
  1452.  
  1453.   A descriptive list uses the description environment.
  1454.  
  1455.   \begin{description}
  1456.   \item{Oven} Dirty, needs new burner.
  1457.   \item{Refrigerator}  Dirty.  Sorry.
  1458.   \item{Sink and drainboard}  Stained, drippy, cold water faucet.
  1459.   \end{description}
  1460.  
  1461.   5.2.4.2.  Letters.
  1462.  
  1463.   The letter class uses special definitions to format business letters.
  1464.  
  1465.   The letter environment takes one argument, the address of the letter's
  1466.   addressee.  The address command, which must appear in the document
  1467.   preamble, defines the return address.  The signature command defines
  1468.   the sender's name as it appears after the closing.
  1469.  
  1470.   The LaTeX source of a simple business letter might look like this.
  1471.  
  1472.   \documentclass[12pt]{letter}
  1473.   \signature{John Q. Public}
  1474.   \address{123 Main St.\\Los Angeles, CA.  96005\\Tel: 123/456-7890}
  1475.   \begin{document}
  1476.   \begin{letter}{ACME Brick Co.\\100 Ash St.\\San Diego, CA 96403}
  1477.   \opening{Dear Sir/Madam:}
  1478.  
  1479.   With regard to one of your bricks that I found on my living room
  1480.   carpet surrounded by shards of my broken front window...
  1481.  
  1482.   (Remainder of the body of the letter.)
  1483.  
  1484.   \closing{Sincerely,}
  1485.  
  1486.   \end{letter}
  1487.   \end{document}
  1488.  
  1489.   Note that the addresses include double backslashes, which specify
  1490.   where the line breaks should occur.
  1491.  
  1492.   5.3.  LaTeX extension packages and other resources.
  1493.  
  1494.   We mentioned above that using underlining as a form of text emphasis
  1495.   presents special problems.  Actually, TeX has no problem underlining
  1496.   text, because it is a convention of mathematical typesetting.  In
  1497.   LaTeX, you can underline words with the command:
  1498.  
  1499.   \underline{text to be underlined}
  1500.  
  1501.   The problem is that underlining will not break across lines, and, in
  1502.   some circumstances, underlining can be uneven.  However, there is a
  1503.   LaTeX macro packagem, ready-made, that makes underlining the default
  1504.   mode of text emphasis.  It's called ulem.sty, and is one of the many
  1505.   contributed LaTeX packages that are freely available via the Internet.
  1506.  
  1507.   To use ulem.sty, include the command
  1508.  
  1509.   \usepackage{ulem}
  1510.  
  1511.   in the document preamble.
  1512.  
  1513.   The LaTeX Catalogue provides one-line descriptions of every LaTeX
  1514.   package available, their names and CTAN paths.  For the URL of the
  1515.   most current edition of the Catalogue, see the section ``Resources for
  1516.   further information''.
  1517.  
  1518.   The packages which are available for LaTeX include:
  1519.  
  1520.      ifthen
  1521.         Include conditional statements in your documents.
  1522.  
  1523.      initials
  1524.         Defines a font for initial dropped capitals.
  1525.  
  1526.      sanskrit
  1527.         Font and preprocessor for producing documents in Sanskrit.
  1528.  
  1529.      recipe
  1530.         A LaTeX2e class to typeset recipes.
  1531.  
  1532.      refman
  1533.         Variant report and article styles.
  1534.  
  1535.   To make the path given in the Catalogue into a fully-qualified URL,
  1536.   concatenate the path to the hostname URL and top-level path of the
  1537.   CTAN archive you wish to contact.  For example, the top-level CTAN
  1538.   directory of the site ftp.tex.ac.uk is ctan/tex-archive.  The complete
  1539.   URL of the directory of the refman package would be:
  1540.  
  1541.   ftp://ftp.tex.ac.uk/ctan/tex-archive/   +
  1542.   macros/latex/contrib/supported/refman   =
  1543.  
  1544.   ftp://ftp.tex.ac.uk/ctan/tex-archive/macros/latex/contrib/supported/refman/
  1545.  
  1546.   Some packages have more than one file, so only the path to the pack¡
  1547.   age's directory is given.
  1548.  
  1549.   When you have the URL in hand, you can retrieve the package from one
  1550.   of the CTAN archive sites listed in section ``Appendix A''.  You can
  1551.   download a complete list of the archive's contents as the file
  1552.   FILES.byname, in the archive's top-level directory.  You can also
  1553.   search the archive on line for a keyword with the ftp(1) command
  1554.  
  1555.   quote site index <keyword>
  1556.  
  1557.   6.  Mixing text and graphics with dvips(1).
  1558.  
  1559.   In general, this section applies to any TeX or LaTeX document which
  1560.   mixes text and graphics.  teTeX, like most other TeX distributions, is
  1561.   configured to request Computer Modern fonts by default.  When printing
  1562.   documents with Type 1 scalable fonts or graphics, font and graphics
  1563.   imaging is the job of dvips(1). dvips(1) can use either Computer
  1564.   Modern bit mapped fonts or Type 1 scalable fonts, or any combination
  1565.   of the two.  First, let's concentrate on printing and previewing some
  1566.   graphics.
  1567.  
  1568.   In general, you will want to follow this procedure any time a LaTeX
  1569.   source document has the statement
  1570.  
  1571.   \includepackage{graphics}
  1572.  
  1573.   in the document preamble.  This statement tells LaTeX to include the
  1574.   text of the graphics.sty package in the source document.  There are
  1575.   other commands to perform graphics operations, and the statements in
  1576.   plain-TeX documents may not clue you in whether you need to use
  1577.   dvips(1). The difference will be apparent in the output, though, when
  1578.   the document is printed with missing figures and other graphics.
  1579.  
  1580.   So, for now, we'll concentrate on printing documents which use the
  1581.   LaTeX graphics.sty package.  You might want to take a look at the
  1582.   original TeX input.  It isn't included in the teTeX distribution, but
  1583.   it is available at
  1584.  
  1585.   ~CTAN/macros/latex/packages/graphics/grfguide.tex.
  1586.  
  1587.   What the teTeX distribution does include is the .dvi output file, and
  1588.   it is already TeXed for you.  There is a reason for this, and it has
  1589.   to do with the necessity of including Type 1 fonts in the output in
  1590.   order for the document to print properly.  If you want to LaTeX
  1591.   grfguide.tex, see the next section.  For now, however, we'll work on
  1592.   getting usable output using dvips(1).
  1593.  
  1594.   The file grfguide.dvi is located in the directory
  1595.  
  1596.   texmf/doc/latex/graphics
  1597.  
  1598.   The first step in outputting grfguide.dvi is to translate it to
  1599.   PostScript.  The program dvips(1) is used for this.  It does just
  1600.   exactly what its name implies.  There are many options available for
  1601.   invoking dvips(1), but the simplest (nearly) form is
  1602.  
  1603.   dvips -f -r <grfguide.dvi >grfguide.ps
  1604.  
  1605.   The -f command switch tells dvips(1) to operate as a filter, reading
  1606.   from standard input and writing to standard output.  dvips(1) output
  1607.   can be configured so its output defaults to lpr(1). (Mine does, which
  1608.   allows me to print directly from dvips(1).)  Post processors like
  1609.   Ghostscript and printing filters like APSFILTER (see section ``''
  1610.   name="APSFILTER"), can be configured for your own needs.  If you need
  1611.   to feed the output manually to a post-processor, the -f option is gen¡
  1612.   erally the first you should include in the dvips(1) command line.
  1613.   This form also seems to be easier to use in shell scripts.
  1614.  
  1615.   If you can print PostScript directly to your printer via lpr(1), you
  1616.   can simply type
  1617.  
  1618.   dvips -r grfguide.dvi
  1619.  
  1620.   The -r option tells dvips to output the pages in reverse order so they
  1621.   stack correctly when they exit a printer.  Use it or not, as appropri¡
  1622.   ate for your output device.
  1623.  
  1624.   Depending on whether you still have the fonts that dvilj2(1) generated
  1625.   from the last document, dvips(1) and metafont may or may not need to
  1626.   create new fonts needed by grfguide.dvi.  Eventually, though, dvips(1)
  1627.   will output a list of the pages translated to PostScript, and you will
  1628.   have your PostScript output ready to be rendered on whatever output
  1629.   device you have available.
  1630.  
  1631.   If you're lucky (and rich), then you have a PostScript-capable printer
  1632.   already and will be able to print grfguide.ps directly.  You can
  1633.   either spool the output to the printer using lpr(1).  If for some
  1634.   reason your printer software doesn't work right with PostScript files,
  1635.   you can, in a pinch, simply dump the file to printer, with
  1636.  
  1637.   cat grfguide.ps >/dev/lp0
  1638.  
  1639.   or whichever port your printer is attached to, though this is not rec¡
  1640.   ommended for everyday use.
  1641.  
  1642.   If you want or need to invoke Ghostscript manually, this is the
  1643.   standard procedure for its operation.  The first thing you want to do
  1644.   is invoke Ghostscript to view its command line arguments, like this:
  1645.  
  1646.   gs -help | less
  1647.  
  1648.   You'll see a list of supported output devices and sundry other com¡
  1649.   mands.  Pick the output device which most nearly matches your printer.
  1650.   On Chanel3, because I generally produce black-and-white text, I use
  1651.   the cdjmono driver, which drives a color Deskjet in monochrome (black
  1652.   and white) mode.
  1653.  
  1654.   The command line I would use is:
  1655.  
  1656.   gs -dNOPAUSE -sDEVICE=cdjmono -sOutputFile=/tmp/gs.out grfguide.ps -c quit
  1657.  
  1658.   This will produce my HP-compatible output in the /tmp directory.  It's
  1659.   a good idea to use a directory like /tmp, because gs(1) can be partic¡
  1660.   ular about access permissions, and you can't (and shouldn't) always
  1661.   count on being logged in as root to perform these steps.  Now you can
  1662.   print the file:
  1663.  
  1664.   lpr /tmp/gs.out
  1665.  
  1666.   Obviously, this can all go into a shell script.  On my system, I have
  1667.   two simple scripts written, pv and pr, which simply outputs the
  1668.   PostScript file either to the display or the printer.  Screen preview¡
  1669.   ing is possible without X, but it's far from ideal.  So, it's defi¡
  1670.   nitely worth the effort to install XFree86, or TinyX (which is what I
  1671.   did) to view the output on the screen.
  1672.  
  1673.   The order of commands in a gs(1) command line is significant, because
  1674.   some of the options tell Ghostscript to look for pieces of PostScript
  1675.   code from its library.
  1676.  
  1677.   The important thing to remember is that grfguide.dvi makes requests
  1678.   for both Computer Modern bit mapped and Type 1 scaled fonts.  If you
  1679.   can mix scalable and bit mapped fonts in a document, you're well on
  1680.   the way to becoming a TeXpert.
  1681.  
  1682.   7.  Using PostScript fonts.
  1683.  
  1684.   It used to be that public domain, Type 1 fonts were much poorer
  1685.   quality than Computer Modern bit mapped fonts.  This situation has
  1686.   improved in the last several years, though, but matching the fonts is
  1687.   up to you.  Having several different font systems on one machine can
  1688.   seem redundant and an unnecessary waste of disk space.  And the
  1689.   Computer Modern fonts can seem, well, a little too formal to be
  1690.   suitable for everyday use.  It reminds me sometimes of bringing out
  1691.   the good China to feed the dog.  At least you don't need to spend a
  1692.   bundle on professional quality fonts any longer.
  1693.  
  1694.   One of the major improvements of LaTeX2e over its predecessor was the
  1695.   inclusion of the New Font Selection Scheme.  (It's now called PSNFSS.)
  1696.   Formerly, TeX authors would specify fonts with commands like
  1697.  
  1698.   \font=bodyroman = cmr10 scaled \magstep 1
  1699.  
  1700.   which provides precision but requires the skills of a type designer
  1701.   and mathematician to make good use of.  Also, it's not very portable.
  1702.   If another system didn't have the font cmr10 (this is TeX nomenclature
  1703.   for Computer Modern Roman, 10 point, with the default medium stroke
  1704.   weight), somebody would have to re-code the fonts specifications for
  1705.   the entire document.  PSNFSS, however, allows you specify fonts by
  1706.   family (Computer Modern, URW Nimbus, Helvetica, Utopia, and so forth),
  1707.   weight (light, medium, bold), orientation (upright or oblique), face
  1708.   (Roman, Italic), and base point size.  (See the section ``Characters
  1709.   and type styles'' for a description of the commands to specify
  1710.   typefaces.)  Many fonts are packaged as families.  For example, a
  1711.   Roman-type font may come packaged with a sans serif font, like
  1712.   Helvetica, and a monospaced font, like Courier.  You, as the author of
  1713.   a LaTeX document, can specify an entire font family with one command.
  1714.  
  1715.   There are, as I said, several high-quality font sets available in the
  1716.   public domain.  One of them is Adobe Utopia.  Another is Bitstream
  1717.   Charter.  Both are commercial quality fonts which have been donated to
  1718.   the public domain.
  1719.  
  1720.   These happen to be two of my favorites.  If you look around one of the
  1721.   CTAN sites, you will find these and other fonts archived there. There
  1722.   are enough fonts around that you'll be able to design documents the
  1723.   way you want them to look, and not just English text, either.  TeX was
  1724.   originally designed for mathematical typesetting, so there is a full
  1725.   range of mathematical fonts available, as well as Cyrillic, Greek,
  1726.   Kana, and other alphabets too numerous to mention.
  1727.  
  1728.   The important thing to look for is files which have either the are the
  1729.   scalable fonts themselves, not simply the metrics files.  Type 1 fonts
  1730.   use .pfm metric files, as opposed to the sets I mentioned above are
  1731.   included in teTeX distributions, as well as separately.
  1732.  
  1733.   What I said above, concerning the ease of font selection under PSNFSS,
  1734.   is true in this instance.  If we want to use the Charter fonts in our
  1735.   document instead of Computer Modern bit mapped, all that is necessary
  1736.   is include the LaTeX statement
  1737.  
  1738.   \renewcommand{\familydefault}{bch}
  1739.  
  1740.   in the document preamble, where ``bch'' is the common designation for
  1741.   Bitstream Charter.  The Charter fonts reside in the directory
  1742.  
  1743.   /usr/lib/teTeX/texmf/fonts/type1/bitstrea/charter
  1744.  
  1745.   There you'll see the .pfb files of the Charter fonts: bchb8a.pfb for
  1746.   Charter Bold, bchr8a.pfb for Charter Roman, bchbi8a.pfb for Charter
  1747.   Bold Italic.  The ``8a'' in the font names indicates the character
  1748.   encoding.  At this point you shouldn't need to worry much about them,
  1749.   because the encodings mostly differ for 8-bit characters, which have
  1750.   numeric values above 128 decimal.  They mostly define accents and non-
  1751.   English characters.  The Type 1 font encodings generally work well for
  1752.   Western alphabets because they conform to the ISO 8859 standards for
  1753.   international character sets, so this is an added benefit of using
  1754.   them.
  1755.   To typeset a document which has Charter fonts selected, you would give
  1756.   the command
  1757.  
  1758.   pslatex document.tex
  1759.  
  1760.   pslatex is a variant of teTeX's standard latex(1) command which
  1761.   defines the directories where the Type 1 fonts are, as well as some
  1762.   additional LaTeX code to load.  You'll see the notice screen for psla¡
  1763.   tex followed by the status output of the TeX job itself.  In a moment,
  1764.   you'll have a .dvi file which includes the Charter font requests.  You
  1765.   can then print the file with dvips(1), and gs(1) if necessary.
  1766.  
  1767.   Installing a Type 1 font set is not difficult, as long as you follow a
  1768.   few basic steps.  You should unpack the fonts in a subdirectory of the
  1769.   /usr/lib/teTeX/texmf/fonts/type1 directory, where your other Type 1
  1770.   fonts are located, and then run texhash to let the directory search
  1771.   routines know that the fonts have been added.  Then you need to add
  1772.   the font descriptions to the file psfonts.map so dvips(1) knows
  1773.   they're on the system.  The format of the psfonts.map file is covered
  1774.   in a couple different places in the references mentioned above.
  1775.   Again, remember to run the texhash program to update the teTeX
  1776.   directory database.
  1777.  
  1778.   It is definitely an advantage to use the X Windows System with teTeX--
  1779.   XFree86 under Linux -- because it allows for superior document
  1780.   previewing.  It's not required, but in general, anything that allows
  1781.   for easier screen previewing is going to benefit your work, in terms
  1782.   of the quality of the output.  However, there is a tradeoff with speed
  1783.   of editing, which is much quicker on character-mode displays.  Having
  1784.   an editor which is slower than molasses in Minnesota can definitely
  1785.   hinder your work.
  1786.  
  1787.   Anyway, whether or not you are able to view documents easily on-
  1788.   screen, please recycle your paper, and use both sides of each sheet.
  1789.   If possible, purchase recycled photocopy paper to print on.  You don't
  1790.   want your workplace to look like a branch office of a paper company.
  1791.  
  1792.   Remember:  Save a tree... kill an editor.
  1793.  
  1794.   Robert Kiesling
  1795.  
  1796.   kiesling@terracom.net
  1797.  
  1798.   8.  Appendix: CTAN Site Listing
  1799.  
  1800.   This is the text of the file CTAN.sites, which is available in the
  1801.   top-level directory of each CTAN archive or mirror site.
  1802.  
  1803.   In order to reduce network load, it is recommended that you use the
  1804.   Comprehensive TeX Archive Network (CTAN) host which is located in the
  1805.   closest network proximity to your site.  Alternatively, you may wish to
  1806.   obtain a copy of the CTAN via CD-ROM (see help/CTAN.cdrom for details).
  1807.  
  1808.   Known mirrors of the CTAN reside on (alphabetically):
  1809.     cis.utovrm.it (Italia)                /TeX
  1810.     ctan.unsw.edu.au (NSW, Australia)     /tex-archive
  1811.     dongpo.math.ncu.edu.tw (Taiwan)       /tex-archive
  1812.     ftp.belnet.be (Belgium)               /packages/TeX
  1813.     ftp.ccu.edu.tw (Taiwan)               /pub/tex
  1814.     ftp.cdrom.com (West coast, USA)       /pub/tex/ctan
  1815.     ftp.comp.hkbu.edu.hk (Hong Kong)      /pub/TeX/CTAN
  1816.     ftp.cs.rmit.edu.au  (Australia)       /tex-archive
  1817.     ftp.cs.ruu.nl (The Netherlands)       /pub/tex-archive
  1818.     ftp.cstug.cz (The Czech Republic)     /pub/tex/CTAN
  1819.     ftp.duke.edu (North Carolina, USA)    /tex-archive
  1820.     ftp.funet.fi (Finland)                /pub/TeX/CTAN
  1821.     ftp.gwdg.de (Deutschland)             /pub/dante
  1822.     ftp.jussieu.fr (France)               /pub4/TeX/CTAN
  1823.     ftp.kreonet.re.kr (Korea)             /pub/CTAN
  1824.     ftp.loria.fr (France)                 /pub/unix/tex/ctan
  1825.     ftp.mpi-sb.mpg.de (Deutschland)       /pub/tex/mirror/ftp.dante.de
  1826.     ftp.nada.kth.se (Sweden)              /pub/tex/ctan-mirror
  1827.     ftp.oleane.net (France)               /pub/mirrors/CTAN/
  1828.     ftp.rediris.es (Espa\~na)             /mirror/tex-archive
  1829.     ftp.rge.com (New York, USA)           /pub/tex
  1830.     ftp.riken.go.jp (Japan)               /pub/tex-archive
  1831.     ftp.tu-chemnitz.de (Deutschland)      /pub/tex
  1832.     ftp.u-aizu.ac.jp (Japan)              /pub/tex/CTAN
  1833.     ftp.uni-augsburg.de (Deutschland)     /tex-archive
  1834.     ftp.uni-bielefeld.de (Deutschland)    /pub/tex
  1835.     ftp.unina.it (Italia)                 /pub/TeX
  1836.     ftp.uni-stuttgart.de (Deutschland)    /tex-archive (/pub/tex)
  1837.     ftp.univie.ac.at (\"Osterreich)       /packages/tex
  1838.     ftp.ut.ee (Estonia)                   /tex-archive
  1839.     ftpserver.nus.sg (Singapore)          /pub/zi/TeX
  1840.     src.doc.ic.ac.uk (England)            /packages/tex/uk-tex
  1841.     sunsite.auc.dk (Denmark)              /pub/tex/ctan
  1842.     sunsite.cnlab-switch.ch (Switzerland) /mirror/tex
  1843.     sunsite.icm.edu.pl (Poland)           /pub/CTAN
  1844.     sunsite.unc.edu (North Carolina, USA) /pub/packages/TeX
  1845.     wuarchive.wustl.edu (Missouri, USA)   /packages/TeX
  1846.  
  1847.   Known partial mirrors of the CTAN reside on (alphabetically):
  1848.     ftp.adfa.oz.au (Australia)            /pub/tex/ctan
  1849.     ftp.fcu.edu.tw (Taiwan)               /pub2/tex
  1850.     ftp.germany.eu.net (Deutschland)      /pub/packages/TeX
  1851.     ftp.gust.org.pl (Poland)              /pub/TeX
  1852.     ftp.jaist.ac.jp (Japan)               /pub/TeX/tex-archive
  1853.     ftp.uu.net (Virginia, USA)            /pub/text-processing/TeX
  1854.     nic.switch.ch (Switzerland)           /mirror/tex
  1855.     sunsite.dsi.unimi.it (Italia)         /pub/TeX
  1856.     sunsite.snu.ac.kr (Korea)             /shortcut/CTAN
  1857.  
  1858.   Please send updates to this list to <ctan@urz.uni-heidelberg.de>.
  1859.  
  1860.   The participating hosts in the Comprehensive TeX Archive Network are:
  1861.     ftp.dante.de  (Deutschland)
  1862.          -- anonymous ftp                 /tex-archive (/pub/tex /pub/archive)
  1863.          -- gopher on node gopher.dante.de
  1864.          -- e-mail via ftpmail@dante.de
  1865.          -- World Wide Web access on www.dante.de
  1866.          -- Administrator: <ftpmaint@dante.de>
  1867.  
  1868.     ftp.tex.ac.uk (England)
  1869.          -- anonymous ftp                 /tex-archive (/pub/tex /pub/archive)
  1870.          -- gopher on node gopher.tex.ac.uk
  1871.          -- NFS mountable from nfs.tex.ac.uk:/public/ctan/tex-archive
  1872.          -- World Wide Web access on www.tex.ac.uk
  1873.          -- Administrator: <ctan-uk@tex.ac.uk>
  1874.  
  1875.